---
title: 範囲・選択・セル
---

## 範囲 [#range]

範囲（Range）とは、ワークシート上の矩形領域であり、開始行番号・開始列番号と縦横の長さ、または開始行番号・開始列番号と終了行番号・終了列番号によって特定されます。

スプレッドシートにおける多くの操作（値の設定／取得、スタイルの設定／取得など）は Range API を通じて実行できます。

### Facade API

範囲関連 Facade API の完全な定義は [FRange FacadeAPI](https://reference.univer.ai/en-US/classes/FRange) を参照してください。

#### 範囲の生成

範囲を取得するには、開始行番号・開始列番号・行数（高さ）・列数（幅）を指定します。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// セル A1 の範囲を生成
const fRange = fWorksheet.getRange(0, 0)
console.log(fRange, fRange.getA1Notation())

// セル A1:B2 の範囲を生成
const fRange2 = fWorksheet.getRange(0, 0, 2, 2)
console.log(fRange2, fRange2.getA1Notation())
```

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// Sheet1 シート上の A1:B2 範囲を取得
const fRange1 = fWorksheet.getRange('Sheet1!A1:B2')
console.log(fRange1, fRange1.getA1Notation())

// 単一セル A1 を取得
const fRange2 = fWorksheet.getRange('A1')
console.log(fRange2, fRange2.getA1Notation())

// A1:B2 範囲を取得
const fRange3 = fWorksheet.getRange('A1:B2')
console.log(fRange3, fRange3.getA1Notation())

// 列 A 全体を取得
const fRange4 = fWorksheet.getRange('A:A')
console.log(fRange4, fRange4.getA1Notation())

// 行 1 全体を取得
const fRange5 = fWorksheet.getRange('1:1')
console.log(fRange5, fRange5.getA1Notation())
```

#### 範囲データの取得

範囲左上セルの値を取得：

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')

console.log(fRange.getValue()) // 範囲左上セルの値
console.log(fRange.getRawValue()) // 範囲左上セルの生値
console.log(fRange.getDisplayValue()) // 範囲左上セルの表示値
console.log(fRange.getCellData()) // 範囲左上セルのセルデータ
console.log(fRange.getRichTextValue()) // 範囲左上セルのリッチテキスト値
console.log(fRange.getRichTextValue().toPlainText()) // リッチテキスト値のプレーンテキスト
```

範囲内すべてのセル値を取得：

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')

console.log(fRange.getValues()) // 全セルの値
console.log(fRange.getRawValues()) // 全セルの生値
console.log(fRange.getDisplayValues()) // 全セルの表示値
console.log(fRange.getCellDatas()) // 全セルのセルデータ
console.log(fRange.getRichTextValues()) // 全セルのリッチテキスト値
```

範囲内の数式を取得：

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')

console.log(fRange.getFormula()) // 範囲左上セルの数式
console.log(fRange.getFormulas()) // 範囲内全セルの数式
```

#### 範囲への値設定

##### 単一値の設定

値またはセルオブジェクトを渡すと、範囲内の全セルがその内容で上書きされます。文字列が `=` で始まる場合は数式として解釈されます。

例: A1:B2 に `Hello, Univer` を設定

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')
fRange.setValue('Hello, Univer')
```

A1+B1 を算出する数式を設定：

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')
fRange.setValue('=A1+B1')
```

セルオブジェクトを設定：

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')
fRange.setValue({
  v: 'Hello, Univer',
  custom: {
    key: 'value',
  },
})
```

範囲左上セルのみ設定したい場合は [`FRange.setValueForCell`](https://reference.univer.ai/en-US/classes/FRange#setvalueforcell)：

```typescript
fRange.setValueForCell('Hello, Univer')
```

##### 配列による複数値設定

渡す二次元配列の行数・列数は範囲の行数・列数と一致している必要があります。

セル値またはセルオブジェクトを使用できます。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')
fRange.setValues([
  ['A1', 'B1'],
  ['A2', 'B2'],
])

fRange.setValues([
  [{ v: 'A1' }, { v: 'B1' }],
  [{ v: 'A2' }, { v: 'B2' }],
])
```

##### オブジェクトによる複数値設定

オブジェクトを渡す場合、第 1 インデックスが行番号、第 2 インデックスが列番号を表し、範囲サイズと一致している必要はありません（指定された座標のみ反映）。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')
fRange.setValues({
  0: {
    0: 'A1',
    1: 'B1',
  },
  1: {
    0: 'A2',
    1: 'B2',
  },
})
```

#### 範囲データのクリア

- [`FRange.clear`](https://reference.univer.ai/en-US/classes/FRange#clear)： コンテンツと書式をすべてクリア
- [`FRange.clearContent`](https://reference.univer.ai/en-US/classes/FRange#clearcontent)： コンテンツのみクリア
- [`FRange.clearFormat`](https://reference.univer.ai/en-US/classes/FRange#clearformat)： 書式のみクリア

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorkSheet = fWorkbook.getActiveSheet()
const fRange = fWorkSheet.getRange('A1:D10')

// コンテンツと書式をクリア
fRange.clear()
```

#### 範囲スタイルの取得

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')
console.log(fRange.getCellStyleData()) // 左上セルのスタイルデータ
console.log(fRange.getCellStyle()) // 左上セルのスタイル
console.log(fRange.getCellStyles()) // 全セルのスタイル
```

#### 範囲スタイルの設定

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')
fRange.setValues([
  [1, 2],
  [3, 4],
]).setFontWeight('bold').setFontLine('underline').setFontFamily('Arial').setFontSize(24).setFontColor('red')
```

#### 範囲スタイルのリセット

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')
fRange
  .setFontWeight(null)
  .setFontLine(null)
  .setFontFamily(null)
  .setFontSize(null)
  .setFontColor(null)
```

#### セル挿入

[`FRange.insertCells`](https://reference.univer.ai/en-US/classes/FRange#insertcells) は指定範囲内に空セルを挿入し、指定次元方向に既存データを押し出します。

```typescript
// アクティブシートは空と仮定
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const values = [
  [1, 2, 3, 4],
  [2, 3, 4, 5],
  [3, 4, 5, 6],
  [4, 5, 6, 7],
  [5, 6, 7, 8],
]

// A1:D5 を初期化
// 1 | 2 | 3 | 4
// 2 | 3 | 4 | 5
// 3 | 4 | 5 | 6
// 4 | 5 | 6 | 7
// 5 | 6 | 7 | 8
const fRange = fWorksheet.getRange('A1:D5')
fRange.setValues(values)
console.log(fWorksheet.getRange('A1:D5').getValues()) // [[1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]]

// A1:B2 に列方向で空セルを挿入
//   |   | 1 | 2
//   |   | 2 | 3
// 3 | 4 | 5 | 6
// 4 | 5 | 6 | 7
// 5 | 6 | 7 | 8
const fRange2 = fWorksheet.getRange('A1:B2')
fRange2.insertCells(univerAPI.Enum.Dimension.COLUMNS)
console.log(fWorksheet.getRange('A1:D5').getValues()) // [[null, null, 1, 2], [null, null, 2, 3], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]]

// 再度 A1:D5 を元に戻す
// 1 | 2 | 3 | 4
// 2 | 3 | 4 | 5
// 3 | 4 | 5 | 6
// 4 | 5 | 6 | 7
// 5 | 6 | 7 | 8
fRange.setValues(values)

// A1:B2 に行方向で空セルを挿入
//   |   | 3 | 4
//   |   | 4 | 5
// 1 | 2 | 5 | 6
// 2 | 3 | 6 | 7
// 3 | 4 | 7 | 8
const fRange3 = fWorksheet.getRange('A1:B2')
fRange3.insertCells(univerAPI.Enum.Dimension.ROWS)
console.log(fWorksheet.getRange('A1:D5').getValues()) // [[null, null, 3, 4], [null, null, 4, 5], [1, 2, 5, 6], [2, 3, 6, 7], [3, 4, 7, 8]]
```

#### セル削除

[`FRange.deleteCells`](https://reference.univer.ai/zh-CN/classes/FRange#deletecells) は指定範囲を削除し、指定次元方向へデータを詰めます。

```typescript
// アクティブシートは空と仮定
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const values = [
  [1, 2, 3, 4],
  [2, 3, 4, 5],
  [3, 4, 5, 6],
  [4, 5, 6, 7],
  [5, 6, 7, 8],
]

// 初期状態
// 1 | 2 | 3 | 4
// 2 | 3 | 4 | 5
// 3 | 4 | 5 | 6
// 4 | 5 | 6 | 7
// 5 | 6 | 7 | 8
const fRange = fWorksheet.getRange('A1:D5')
fRange.setValues(values)
console.log(fWorksheet.getRange('A1:D5').getValues()) // [[1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]]

// A1:B2 を列方向で削除
// 3 | 4 |   |
// 4 | 5 |   |
// 3 | 4 | 5 | 6
// 4 | 5 | 6 | 7
// 5 | 6 | 7 | 8
const fRange2 = fWorksheet.getRange('A1:B2')
fRange2.deleteCells(univerAPI.Enum.Dimension.COLUMNS)
console.log(fWorksheet.getRange('A1:D5').getValues()) // [[3, 4, null, null], [4, 5, null, null], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8]]

// 再設定
// 1 | 2 | 3 | 4
// 2 | 3 | 4 | 5
// 3 | 4 | 5 | 6
// 4 | 5 | 6 | 7
// 5 | 6 | 7 | 8
fRange.setValues(values)

// A1:B2 を行方向で削除
// 3 | 4 | 3 | 4
// 4 | 5 | 4 | 5
// 5 | 6 | 5 | 6
//   |   | 6 | 7
//   |   | 7 | 8
const fRange3 = fWorksheet.getRange('A1:B2')
fRange3.deleteCells(univerAPI.Enum.Dimension.ROWS)
console.log(fWorksheet.getRange('A1:D5').getValues()) // [[3, 4, 3, 4], [4, 5, 4, 5], [5, 6, 5, 6], [null, null, 6, 7], [null, null, 7, 8]]
```

#### セル結合

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// B1:B2 を結合
const fRange = fWorksheet.getRange('B1:B2')
fRange.merge()
console.log(fRange.isMerged()) // true

// A1:B2 について
const fRange2 = fWorksheet.getRange('A1:B2')
console.log(fRange2.isMerged()) // false
console.log(fRange2.isPartOfMerge()) // true

// 結合解除
fRange2.breakApart()

// 水平結合：fRange2.mergeAcross();
// 垂直結合：fRange2.mergeVertically();
// シート内の全結合範囲取得：fWorksheet.getMergedRanges();
```

#### 範囲のハイライト

[`FRange.highlight`](https://reference.univer.ai/en-US/classes/FRange#highlight) は指定スタイルと主セル（primary cell）で範囲を強調表示します。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// 既定スタイルで C3:E5 をハイライト
const fRange = fWorksheet.getRange('C3:E5')
fRange.highlight()

// カスタムスタイル＋主セル D8 で C7:E9 をハイライト
const fRange2 = fWorksheet.getRange('C7:E9')
const primaryCell = fWorksheet.getRange('D8').getRange()
const disposable = fRange2.highlight(
  {
    stroke: 'red',
    fill: 'yellow',
  },
  {
    ...primaryCell,
    actualRow: primaryCell.startRow,
    actualColumn: primaryCell.startColumn,
  },
)

// 5 秒後に C7:E9 のハイライト解除
setTimeout(() => {
  disposable.dispose()
}, 5000)
```

#### テキストを列に分割

[`FRange.splitTextToColumns`](https://reference.univer.ai/en-US/classes/FRange#splittexttocolumns) は指定した区切り文字に従いテキストを複数列へ分割します。

デフォルト区切り文字の例:

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// A1:A3 の値:
//  A      |
//  1,2,3  |
//  4,,5,6 |
const fRange = fWorksheet.getRange('A1:A3')
fRange.setValues([
  ['A'],
  ['1,2,3'],
  ['4,,5,6'],
])

// splitTextToColumns(true) 呼び出し後:
//  A |   |
//  1 | 2 | 3
//  4 | 5 | 6
fRange.splitTextToColumns(true)

// splitTextToColumns(false) 呼び出し後:
//  A |   |   |
//  1 | 2 | 3 |
//  4 |   | 5 | 6
fRange.splitTextToColumns(false)
```

特定区切り文字の例:

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// A1:A3：
//     A   |
//  1;;2;3 |
//  1;,2;3 |
const fRange = fWorksheet.getRange('A1:A3')
fRange.setValues([
  ['A'],
  ['1;;2;3'],
  ['1;,2;3'],
])

// セミコロン + カンマで分割（空要素保持 = false），結果：
//  A |   |   |
//  1 |   | 2 | 3
//  1 |   | 2 | 3
fRange.splitTextToColumns(false, univerAPI.Enum.SplitDelimiterType.Semicolon | univerAPI.Enum.SplitDelimiterType.Comma)

// 空要素圧縮 = true，結果：
//  A |   |
//  1 | 2 | 3
//  1 | 2 | 3
fRange.splitTextToColumns(true, univerAPI.Enum.SplitDelimiterType.Semicolon | univerAPI.Enum.SplitDelimiterType.Comma)
```

カスタム区切り文字の例:

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// A1:A3：
//     A   |
//  1#2#3  |
//  4##5#6 |
const fRange = fWorksheet.getRange('A1:A3')
fRange.setValues([
  ['A'],
  ['1#2#3'],
  ['4##5#6'],
])

// カスタム '#'、空要素保持 = false
//  A |   |   |
//  1 | 2 | 3 |
//  4 |   | 5 | 6
fRange.splitTextToColumns(false, univerAPI.Enum.SplitDelimiterType.Custom, '#')

// 空要素圧縮 = true
//  A |   |
//  1 | 2 | 3
//  4 | 5 | 6
fRange.splitTextToColumns(true, univerAPI.Enum.SplitDelimiterType.Custom, '#')
```

#### 範囲の座標取得

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')
console.log(fRange.getCellRect()) // width、heigh、left、right、top、bottom、x、y
```

#### 結合情報と座標の同時取得

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')
console.log(fRange.getCell())
```

## 選択 [#selection]

Univer Sheets は複数の離散的な選択範囲（マルチセレクション）をサポートしており、選択集合は Range の配列です。各要素は Range API を通じて操作できます。

また、現在の選択の取得・選択状態の設定・選択変更イベントの監視用 API も提供しています。

### Facade API

選択関連 Facade API の完全な定義は [FSelection FacadeAPI](https://reference.univer.ai/en-US/classes/FSelection) を参照してください。

#### アクティブ選択の取得

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// A1:B2 を新たにアクティブ選択にする
const fRange = fWorksheet.getRange('A1:B2')
fRange.activate()

// 現在のアクティブ選択を取得
const fSelection = fWorksheet.getSelection()
console.log(fSelection)
const activeRange = fSelection.getActiveRange()
console.log(activeRange.getA1Notation()) // A1:B2
```

#### 選択の設定

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// FRange で A1:B2 を選択
const fRange = fWorksheet.getRange('A1:B2')
fRange.activate()

// FWorksheet で C1:D2 に切替
fWorksheet.setActiveSelection(fWorksheet.getRange('C1:D2'))
```

#### 現在セルの取得

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// A10:B11 をアクティブ選択
const fRange = fWorksheet.getRange('A10:B11')
fRange.activate()

// 現在のアクティブセル
let fSelection = fWorksheet.getSelection()
const { actualRow, actualColumn } = fSelection.getCurrentCell()
console.log(fWorksheet.getRange(actualRow, actualColumn).getA1Notation()) // A10

// アクティブセルを B11 に更新
fSelection = fSelection.updatePrimaryCell(fWorksheet.getRange('B11'))
const { actualRow: newRow, actualColumn: newColumn } = fSelection.getCurrentCell()
console.log(fWorksheet.getRange(newRow, newColumn).getA1Notation()) // B11
```

#### 選択の無効化／有効化／非表示／再表示

無効化すると選択操作に反応しません。非表示（transparent）は動作自体は有効なまま可視描画のみ消えます。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()

// 無効化
fWorkbook.disableSelection()

// 有効化
fWorkbook.enableSelection()

// 非表示
fWorkbook.transparentSelection()

// 再表示
fWorkbook.showSelection()
```

#### 選択変更の監視

```typescript
univerAPI.addEvent(univerAPI.Event.SelectionChanged, (params) => {
  const { worksheet, workbook, selections } = params
  console.log(params)
})
```

## セル [#cell]

セルデータはワークシート内部で二次元 Map として保持され、第 1・第 2 インデックスがそれぞれ行番号・列番号に対応します。

典型的なセルオブジェクト例:

```typescript
const data = {
  v: 'Hello, Univer',
  s: 'styleId',
  t: CellValueType.STRING,
}
```

フィールド詳細は [Configure Cell Data](/guides/sheets/model/cell-data) を参照してください。

### 補足

1. セル操作は高さ 1・幅 1 の範囲操作とみなせます。範囲操作については [Range](/guides/sheets/features/core/range-selection#range) を参照。
2. Univer API プラグインは拡張セル属性を `Workbook` の `resources` プロパティにも格納します。詳細は [Plugin Custom Model](/guides/customization/model/) を参照。

## イベント一覧

セル関連で利用可能なイベント一覧:

| Event Name | 説明 | パラメータ型 | 使用例 |
|------------|------|--------------|--------|
| `CellPointerMove` | マウスがセル上を移動したとき | `ICellEventParam` | `const { worksheet, workbook, row, column } = params` |
| `CellPointerDown` | セル上でマウスボタン押下 | `ICellEventParam` | 同上 |
| `CellPointerUp` | セル上でマウスボタン解放 | `ICellEventParam` | 同上 |
| `CellHover` | セル上にホバー | `ICellEventParam` | 同上 |
| `DragOver` | セル上でドラッグオーバー | `ICellEventParam` | 同上 |
| `Drop` | セル上にドロップ | `ICellEventParam` | 同上 |
| `CellClicked` | セルがクリックされた | `ICellEventParam` | 同上 |
| `BeforeSheetEditStart` | セル編集開始前 | `IBeforeSheetEditStartEventParams` | `const { worksheet, workbook, row, column, eventType, keycode, isZenEditor } = params` |
| `SheetEditStarted` | セル編集開始時 | `ISheetEditStartedEventParams` | 同上 |
| `SheetEditChanging` | 編集中内容変更 | `ISheetEditChangingEventParams` | `const { worksheet, workbook, row, column, value, isZenEditor } = params` |
| `BeforeSheetEditEnd` | セル編集終了直前 | `IBeforeSheetEditEndEventParams` | `const { worksheet, workbook, row, column, value, eventType, keycode, isZenEditor, isConfirm } = params` |
| `SheetEditEnded` | セル編集終了後 | `ISheetEditEndedEventParams` | 同上 |

### 使用パターン

全イベントは `addEvent` で監視可能:

```typescript
univerAPI.addEvent(univerAPI.Event.EventName, (params) => {
  // ハンドリング
})
```

### Cell PointerMove イベント

`CellPointerMove` イベントは、マウスカーソルがセル上を移動した際にトリガーされます。現在ポインタ直下にあるセル情報を提供します。

```typescript
univerAPI.addEvent(univerAPI.Event.CellPointerMove, (params) => {
  // イベントパラメータ取得
  const { worksheet, workbook, row, column } = params
  console.log('Current cell position:', worksheet.getRange(row, column).getA1Notation())
})
```

### Cell PointerDown イベント

`CellPointerDown` イベントは、セル上でマウスボタンが押下されたときにトリガーされます。

```typescript
univerAPI.addEvent(univerAPI.Event.CellPointerDown, (params) => {
  const { worksheet, workbook, row, column } = params
  console.log('Mouse down cell:', worksheet.getRange(row, column).getA1Notation())
})
```

### Cell PointerUp イベント

`CellPointerUp` イベントは、セル上でマウスボタンが解放されたときにトリガーされます。

```typescript
univerAPI.addEvent(univerAPI.Event.CellPointerUp, (params) => {
  const { worksheet, workbook, row, column } = params
  console.log('Mouse up cell:', worksheet.getRange(row, column).getA1Notation())
})
```

### Cell Hover イベント

`CellHover` イベントは、マウスがセル上にホバーした時点でトリガーされます。

```typescript
univerAPI.addEvent(univerAPI.Event.CellHover, (params) => {
  const { worksheet, workbook, row, column } = params
  console.log('Hovered cell:', worksheet.getRange(row, column).getA1Notation())
})
```

### Cell DragOver イベント

`DragOver` イベントは、ドラッグ中の要素がセル領域上を通過したときにトリガーされます。

```typescript
univerAPI.addEvent(univerAPI.Event.DragOver, (params) => {
  const { worksheet, workbook, row, column } = params
  console.log('Drag over cell:', worksheet.getRange(row, column).getA1Notation())
})
```

### Cell Drop イベント

`Drop` イベントは、ドラッグ要素がセル上にドロップされた際にトリガーされます。

```typescript
univerAPI.addEvent(univerAPI.Event.Drop, (params) => {
  const { worksheet, workbook, row, column } = params
  console.log('Drop target cell:', worksheet.getRange(row, column).getA1Notation())
})
```

### Cell Click イベント

`CellClicked` イベントは、セルがクリックされたときにトリガーされます。

```typescript
univerAPI.addEvent(univerAPI.Event.CellClicked, (params) => {
  const { worksheet, workbook, row, column } = params
  console.log('Clicked cell:', worksheet.getRange(row, column).getA1Notation())
})
```

### Cell Render イベント

`onCellRender` イベントはセル描画処理中にトリガーし、カスタム描画を挿入できます。

例 1: 固定位置レンダリング（行追加などによる位置変動なし）

```typescript
// 固定位置レンダリング
univerAPI.getSheetHooks().onCellRender([{
  drawWith: (ctx, info, skeleton, spreadsheets) => {
    const { row, col } = info
    // 位置 (1,1) にチェックマークを描画
    if (row === 1 && col === 1) {
      const { primaryWithCoord } = info
      const { startX, startY } = primaryWithCoord
      ctx.fillText('✅', startX, startY + 10)
    }
  },
}])

// 再描画反映
univerAPI.getActiveWorkbook().getActiveSheet().refreshCanvas()
```

例 2: マーカー方式（行／列シフトに追随）

```typescript
// マーカー設定
univerAPI.getActiveWorkbook().getActiveSheet().getRange('B2').setValue({ custom: { key: 'needCheck' } })

// マーカーに基づき描画
univerAPI.getSheetHooks().onCellRender([{
  drawWith: (ctx, info, skeleton, spreadsheets) => {
    const { row, col, data } = info
    // マーカーを持つセルにチェックマークを描画
    if (data?.custom?.key === 'needCheck') {
      const { primaryWithCoord } = info
      const { startX, startY } = primaryWithCoord
      ctx.fillText('✅', startX, startY + 10)
    }
  },
}])

// 再描画
univerAPI.getActiveWorkbook().getActiveSheet().refreshCanvas()
```

### セル編集イベント

#### 編集開始

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.startEditing()
```

#### 編集終了

```typescript
// true で確定、false でキャンセル
// 非同期関数のため await が必要
const fWorkbook = univerAPI.getActiveWorkbook()
await fWorkbook.endEditingAsync(true)
```

#### 編集開始イベント

`BeforeSheetEditStart` はセル編集が開始される直前にトリガーされます。

```typescript
univerAPI.addEvent(univerAPI.Event.BeforeSheetEditStart, (params) => {
  const { worksheet, workbook, row, column, eventType, keycode, isZenEditor } = params
  console.log('Before cell edit:', params)

  // 編集状態遷移を阻止する場合
  params.cancel = true
})
```

`SheetEditStarted` はセル編集開始時にトリガーされます。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetEditStarted, (params) => {
  const { worksheet, workbook, row, column, eventType, keycode, isZenEditor } = params
  console.log(params)
})

// disposable.dispose() で解除
```

#### End Editing Event

The `BeforeSheetEditEnd` event is triggered before cell editing ends.

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetEditEnd, (params) => {
  const { worksheet, workbook, row, column, value, eventType, keycode, isZenEditor, isConfirm } = params
  console.log(params)

  // Cancel the cell edit end operation
  params.cancel = true
})

// disposable.dispose() で解除
```

The `SheetEditEnded` event is triggered after cell editing ends.

```typescript
univerAPI.addEvent(univerAPI.Event.SheetEditEnded, (params) => {
  const { worksheet, workbook, row, column, eventType, keycode, isZenEditor, isConfirm } = params
  console.log('After cell edit:', params)
})
```

### クリップボードイベント

#### BeforeClipboardChange

`BeforeClipboardChange` イベントは、クリップボード内容が変更される直前にトリガーされます。変更前の内容監視や上書き制御に利用できます。

```typescript
univerAPI.addEvent(univerAPI.Event.BeforeClipboardChange, (params) => {
  const { text, html } = params
  console.log('Clipboard content:', text, html)
  // 貼り付けをキャンセルする場合：
  // params.cancel = true;
})
```

#### BeforeClipboardPaste

`BeforeClipboardPaste` イベントは貼り付け実行直前にトリガーされます。貼り付け内容の検査・変換・拒否に利用できます。

```typescript
univerAPI.addEvent(univerAPI.Event.BeforeClipboardPaste, (params) => {
  const { text, html } = params
  console.log('Content to paste:', text, html)
  // 貼り付けをキャンセルする場合：
  // params.cancel = true;
})
```

#### ClipboardChanged

`ClipboardChanged` イベントはクリップボード内容の変更後にトリガーされます。

```typescript
univerAPI.addEvent(univerAPI.Event.ClipboardChanged, (params) => {
  const { text, html } = params
  console.log('New clipboard content:', text, html)
})
```

#### ClipboardPasted

`ClipboardPasted` イベントは貼り付け操作完了後にトリガーされます。

```typescript
univerAPI.addEvent(univerAPI.Event.ClipboardPasted, (params) => {
  const { text, html } = params
  console.log('Pasted content:', text, html)
})
```

## その他

### セルエディタ内の内容をリアルタイム取得するには？

Univer Sheets のセルエディタは Univer Docs エディタエンジン上に構築されており、Facade API を通じアクティブな Univer Docs エディタのスナップショットを取得できます。これによりリアルタイム解析が可能です。

```typescript
univerAPI.onCommandExecuted((command) => {
  const { id } = command
  if (id === 'doc.command.insert-text' || id === 'doc.command.delete-text') {
    const doc = univerAPI.getActiveDocument()
    if (doc) {
      const snapshot = doc.getSnapshot()
      console.log(snapshot.body?.dataStream)
    }
  }
})
```

参考：https://github.com/dream-num/univer/discussions/2261

### セルエディタがフォーカス中に外部ボタン操作でイベントをトリガーされも、スナップショットに編集中セルの内容が含まれない

セルデータはエディタがフォーカスを失ったタイミング（編集終了）で同期されます。取得前に明示的に編集を終了させてください。

```typescript
import '@univerjs/sheets-ui/facade'

$btn.addEventListener('click', () => {
  univerAPI.getActiveWorkbook().endEditingAsync(true)
})
```

参考：https://github.com/dream-num/univer/issues/1314

### Facade API で Workbook を生成直後に一部 API が動作しない

一部 API は UI の完全レンダリング後でないと機能しません。`Rendered` または `Steady` ライフサイクル段階で処理を行うことを推奨します。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {
  if (stage === univerAPI.Enum.LifecycleStages.Steady) {
    // 実行コード
  }
})

// disposable.dispose() で解除
```

参考：[Lifecycle](/guides/sheets/getting-started/lifecycle)
